aliases:
- Obsidian Style Guide
description: This page explains the style guide for writing our support documentation.
publish: true
mobile: true
permalink: style-guide
The Obsidian documentation uses the Google developer documentation style guide. For any topics not covered by the Google style guide, use the Microsoft Style Guide.
This page lists any deviations from the Google style guide, or terminology worth highlighting.
Most of the documentation existed before this style guide did. If you find any violations of this style guide, please create an issue or submit a pull request to obsidianmd/obsidian-docs.
For our English documentation, it is recommended to use Global English to better serve our worldwide audience.
Obsidian product names start with "Obsidian", for example "Obsidian Publish" and "Obsidian Sync".
If a paragraph becomes overly repetitive, you can use the short form in subsequent references.
For example:
To allow device-specific configuration, Obsidian Sync doesn't sync its own settings. You need to configure Sync for each of your devices.
When referring to multiple UI interactions in a sequence, use the → (U+2192) symbol. For example, "Settings → Community plugins".
When moving between notes, use "open" if the destination is hidden, and "switch" if both source and destination notes are open in separate splits.
When possible, any settings should be documented within Obsidian using a descriptive text. Avoid documenting a specific setting in Obsidian Help unless:
Consider using a tip callout if you want to draw attention to a specific setting.
Hyphenate directional terms when using them as adjectives. Avoid hyphenation when direction is used as a noun.
Recommended:
Not recommended:
Prefer "upper-left" and "upper-right" over "top-left" and "top-right".
Don't indicate a direction when referring to settings. The location of the settings control depends on the device.
Recommended:
Not recommended:
Use imperatives for the names of guides, section headings, and step-by-step instructions. The imperative mood is concise and action-oriented, which is more straightforward for users following instructions.
Prefer sentence case over title case for headings, buttons, and titles. When referencing UI elements always match the case of the text in the UI.
Recommended:
Not recommended:
Prefer realistic examples over nonsense terms.
Recommended:
task:(call OR schedule)
Not recommended:
task:(foo OR bar)
When referring to a character on the keyboard by name, add the character between parentheses right after the name:
Recommended:
Not recommended:
-
in front of the word.Use newlines between Markdown blocks:
Recommended:
# Heading 1
This is a section.
1. First item
2. Second item
3. Third item
Not recommended:
# Heading 1
This is a section.
1. First item
2. Second item
3. Third item
Use "width x height pixels" for describing image or screen dimensions.
Example:
Recommended image dimensions: 1920 x 1080 pixels.
Include icons and images when they make it easier to explain things that are hard to describe with words, or when you need to show important parts of the Obsidian application. You can save images in the Attachments
folder.
The image should make the text it accompanies easier to understand.
Example: Once enabled, the Word count plugin will create a new entry on your bottom statusbar.
.png
or .svg
format.Lucide and custom Obsidian icons can be used alongside detailed elements to provide a visual representation of a feature.
Example: In the ribbon on the left, select Create new canvas ( ) to create a canvas in the same folder as the active file.
Guidelines for icons
Attachments/icons
folder.lucide-
before the Lucide icon name.obsidian-icon-
before the Obsidian icon name.Example: The icon for creating a new canvas should be named lucide-layout-dashboard
.
18
pixels in width, 18
pixels in height, and have a stroke width of 1.5
. You can adjust these settings in the SVG data.<svg xmlns="http://www.w3.org/2000/svg" width="WIDTH" height="HEIGHT" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="STROKE-WIDTH" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-layout-dashboard"><rect width="7" height="9" x="3" y="3" rx="1"/><rect width="7" height="5" x="14" y="3" rx="1"/><rect width="7" height="9" x="14" y="12" rx="1"/><rect width="7" height="5" x="3" y="16" rx="1"/></svg>
icon
anchor in embedded images, to tweak the spacing around the icon so that it aligns neatly with the text in the vicinity.Example: ( ![[lucide-cog.svg#icon]] )
Image anchors tags are available to add decorative changes to the embedded images.
The icon anchor tags will not display correctly in Live preview. Use Reading view to confirm the anchor tag has been applied.
Icon
![[lucide-menu.svg#icon]]
The icon anchor tag ensures correct vertical alignment for icons used to indicate interface elements.
The first menu icon uses the anchor tag ( ), while the second menu icon (
) does not.
Interface
![[Vault picker.png#interface]]
The interface anchor tag adds a decorative box shadow around the image. In the first image, the interface anchor tag is applied.
In contrast, the second image does not have the interface anchor applied.
Outline
![[Backlinks.png#outline]]
The outline anchor tag adds a subtle border around the image. In the first image, the outline anchor tag is applied.
The second image lacks the outline anchor tag.
Images slow the loading time of the page, and take valuable Publish storage space. Optimizing images allows a reduction in file size, but maintains the visual integrity of the image.
Both images and icons should be optimized.
Here are a some recommended programs for reducing the size of your images.
We recommend an optimization rate of 65-75%.
Before submitting your Pull Request, please check for any broken links in the documentation of the translation you are working on and correct them. Broken links can occur naturally over time, so verifying their accuracy helps maintain the quality of the documentation.
You can check for broken links using Community plugins or tools available in your IDE.
This documentation is edited on GitHub and hosted online via Obsidian Publish, which includes descriptions for social cards and other SEO elements.
If the page you are working on does not have a description
property, please add one. The description should be 150 characters or fewer and provide an objective summary of the page’s content.
Good: Learn to create templates that capture and organize web page metadata automatically with Web Clipper.
Could be tweaked: Learn how to create templates that automatically capture and organize metadata from web pages with Web Clipper.
When writing or rewriting Instructions on how to perform an action within the app, be sure to include steps for both the mobile and desktop versions.
If you do not have access to a mobile or desktop device, please mention this when submitting your Pull Request.
Translate the entirety of the content when completing a translation. This includes and is not limited to: